feat: implement shared backend interface and selection model by niteshpurohit · Pull Request #487 · Code-Vedas/karya

niteshpurohit · 2026-05-02T15:51:19Z

Added a shared Karya::Backend contract with identifier normalization, backend descriptors, lifecycle hooks, and the minimal InMemory backend wrapper.
Implemented Karya::Backend::Selection as the shared backend identifier model for in_memory, sqlite, redis, postgres, and mysql.
Kept the contract identifier-based: removed backend classification/capability reporting from this PR and aligned docs to the implemented selection model.
Preserved direct queue-store validation semantics in Backend::InMemory#build_queue_store and hardened the supervisor signal path so runtime phase writes are best-effort only after the runtime claim exists.
Added and updated Ruby, RBS, docs, and spec coverage for the shared backend interface and selection model.

closes: #105

- Added a new Backend module to encapsulate backend selection logic. - Introduced classes for Capabilities, Descriptor, and InMemory backend. - Implemented a Selection class for normalizing backend identifiers. - Defined RBS types for backend identifiers and classifications. - Updated documentation to reflect new backend selection contracts. - Added tests for backend capabilities, descriptor, and selection logic. closes: #105

Copilot

Pull request overview

This PR introduces the first shared backend contract in core/karya, adding a backend namespace that describes backend identity, capability reporting, lifecycle hooks, and identifier normalization on top of the existing queue-store layer. It also adds mirrored RBS and focused specs so later adapter/framework work can target one common backend selection model instead of ad hoc conventions.

Changes:

Add Karya::Backend runtime types for backend selection, descriptors, capabilities, a base contract, and an InMemory backend wrapper.
Add mirrored RBS for backend identifiers/classifications and the new backend classes/modules.
Add backend-focused specs and update review/RBS instructions to tighten how accepted input surfaces should be modeled.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
`core/karya/spec/karya/backend/selection_spec.rb`	Adds specs for backend identifier normalization, classification, and support checks.
`core/karya/spec/karya/backend/in_memory_spec.rb`	Adds specs for the new in-memory backend descriptor, queue-store construction, and lifecycle hooks.
`core/karya/spec/karya/backend/descriptor_spec.rb`	Adds specs for descriptor normalization and validation behavior.
`core/karya/spec/karya/backend/capabilities_spec.rb`	Adds specs for capability flag validation and parity exception handling.
`core/karya/spec/karya/backend/base_spec.rb`	Adds specs for the shared backend base contract and descriptor delegation.
`core/karya/sig/karya/backend/selection.rbs`	Declares RBS for backend selection normalization and classification helpers.
`core/karya/sig/karya/backend/in_memory.rbs`	Declares RBS for the concrete in-memory backend wrapper.
`core/karya/sig/karya/backend/descriptor.rbs`	Declares RBS for backend descriptors.
`core/karya/sig/karya/backend/capabilities.rbs`	Declares RBS for backend capability metadata.
`core/karya/sig/karya/backend/base.rbs`	Declares the shared backend interface in RBS.
`core/karya/sig/karya/backend.rbs`	Adds top-level backend namespace and backend-selection error classes to RBS.
`core/karya/sig/karya.rbs`	Adds backend identifier/classification type aliases used by the new backend API.
`core/karya/lib/karya/backend/selection.rb`	Implements backend identifier aliasing, normalization, and deployment classification helpers.
`core/karya/lib/karya/backend/in_memory.rb`	Adds the first concrete backend wrapper around `QueueStore::InMemory`.
`core/karya/lib/karya/backend/descriptor.rb`	Implements backend descriptor normalization and validation.
`core/karya/lib/karya/backend/capabilities.rb`	Implements immutable-ish backend capability metadata and validation.
`core/karya/lib/karya/backend/base.rb`	Introduces the shared backend contract and default lifecycle hooks.
`core/karya/lib/karya/backend.rb`	Adds the backend namespace, errors, and autoload wiring.
`core/karya/lib/karya.rb`	Loads the new backend namespace from the main library entrypoint.
`.github/instructions/review.instructions.md`	Updates review guidance for accepted input surfaces and shared-contract RBS exactness.
`.github/instructions/core-karya-rbs.instructions.md`	Updates Core Karya RBS instructions with backend-input and shared-contract typing rules.

Copilot

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 3 comments.

Copilot

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 4 comments.

Copilot

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 5 comments.

Copilot

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 6 comments.

Copilot

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 5 comments.

Copilot

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 4 comments.

Copilot

Pull request overview

Copilot reviewed 25 out of 25 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (1)

docs/pages/backends.md:33

This section is now titled "Backend Identifiers", but the table still lists display names like Postgres, Redis, MySQL, and SQLite. The new Selection contract only accepts the lowercase identifiers (postgres, redis, mysql, sqlite), so presenting the title-cased names here will mislead readers into using values that the code rejects.

## Backend Identifiers

| Backend    | Position                      | Typical Fit                                            |
| ---------- | ----------------------------- | ------------------------------------------------------ |
| Postgres   | Default production backend    | General-purpose production deployments                 |
| Redis      | Supported production backend  | Queue-centric, low-latency operational workloads       |
| MySQL      | Supported production backend  | SQL environments standardized on MySQL                 |
| SQLite     | Supported constrained backend | Embedded, single-node, or lightweight SQL deployments  |
| `InMemory` | Local/dev/test backend        | Examples, development, tests, and ephemeral evaluation |

Copilot

Pull request overview

Copilot reviewed 25 out of 25 changed files in this pull request and generated 5 comments.

Copilot

Pull request overview

Copilot reviewed 30 out of 30 changed files in this pull request and generated 4 comments.

Copilot

Pull request overview

Copilot reviewed 25 out of 25 changed files in this pull request and generated 8 comments.

niteshpurohit self-assigned this May 2, 2026

Copilot AI review requested due to automatic review settings May 2, 2026 15:51

github-actions Bot added the feature label May 2, 2026

Copilot started reviewing on behalf of niteshpurohit May 2, 2026 15:51 View session

Copilot AI reviewed May 2, 2026

View reviewed changes

Comment thread core/karya/lib/karya/backend/selection.rb Outdated

Comment thread core/karya/sig/karya.rbs Outdated

Comment thread core/karya/sig/karya/backend/descriptor.rbs Outdated

Comment thread core/karya/sig/karya/backend/in_memory.rbs Outdated

feat: refine backend selection model and identifiers

3fda5e6

niteshpurohit requested a review from Copilot May 2, 2026 16:09

Copilot started reviewing on behalf of niteshpurohit May 2, 2026 16:09 View session

Copilot AI reviewed May 2, 2026

View reviewed changes

Comment thread core/karya/lib/karya/backend/descriptor.rb Outdated

Comment thread core/karya/lib/karya/backend/selection.rb Outdated

Comment thread core/karya/sig/karya.rbs Outdated

feat: enhance backend identifier normalization

f305c5a

niteshpurohit requested a review from Copilot May 2, 2026 16:25

Copilot started reviewing on behalf of niteshpurohit May 2, 2026 16:26 View session

Copilot AI reviewed May 2, 2026

View reviewed changes

Comment thread core/karya/sig/karya.rbs Outdated

Comment thread core/karya/lib/karya/backend/descriptor.rb Outdated

Comment thread core/karya/lib/karya/backend/capabilities.rb Outdated

Comment thread core/karya/lib/karya/backend/descriptor.rb Outdated

feat: enhance backend capabilities and descriptor validation

e4295fc

niteshpurohit requested a review from Copilot May 2, 2026 16:38

Copilot started reviewing on behalf of niteshpurohit May 2, 2026 16:39 View session

Copilot AI reviewed May 2, 2026

View reviewed changes

feat: enhance backend capabilities and descriptor validation

e357611

niteshpurohit requested a review from Copilot May 2, 2026 17:22

Copilot started reviewing on behalf of niteshpurohit May 2, 2026 17:22 View session

Copilot AI reviewed May 2, 2026

View reviewed changes

feat: enhance backend identifier handling and classifications

8dd46f4

niteshpurohit requested a review from Copilot May 2, 2026 17:47

Copilot started reviewing on behalf of niteshpurohit May 2, 2026 17:47 View session

Copilot AI reviewed May 2, 2026

View reviewed changes

feat: implement shared backend interface and selection model

9c646d1

niteshpurohit requested a review from Copilot May 2, 2026 18:02

Copilot started reviewing on behalf of niteshpurohit May 2, 2026 18:03 View session

Copilot AI reviewed May 2, 2026

View reviewed changes

Comment thread core/karya/lib/karya/backend/descriptor.rb Outdated

Comment thread core/karya/lib/karya/backend/in_memory.rb Outdated

Comment thread core/karya/lib/karya/backend/base.rb

Comment thread core/karya/lib/karya/backend/selection.rb Outdated

niteshpurohit added 2 commits May 2, 2026 14:17

feat: enhance shutdown signal handling and testing

f096844

feat: refactor backend interface and capabilities

c85f161

Copilot AI review requested due to automatic review settings May 2, 2026 18:35

Copilot started reviewing on behalf of niteshpurohit May 2, 2026 18:35 View session

Copilot AI reviewed May 2, 2026

View reviewed changes

Comment thread core/karya/lib/karya/backend/in_memory.rb Outdated

Comment thread core/karya/lib/karya/worker_supervisor.rb Outdated

Comment thread core/karya/lib/karya/worker_supervisor.rb Outdated

Comment thread core/karya/lib/karya/backend.rb Outdated

feat: enhance backend interface and signal handling

2c57b28

niteshpurohit requested a review from Copilot May 2, 2026 18:56

Copilot started reviewing on behalf of niteshpurohit May 2, 2026 18:56 View session

Copilot AI reviewed May 2, 2026

View reviewed changes

feat: enhance backend interface and error handling

4e70de7

niteshpurohit requested a review from Copilot May 2, 2026 19:25

Copilot started reviewing on behalf of niteshpurohit May 2, 2026 19:25 View session

Copilot AI reviewed May 2, 2026

View reviewed changes

Comment thread core/karya/lib/karya/backend/in_memory.rb Outdated

Comment thread core/karya/sig/karya/worker_supervisor.rbs

Comment thread core/karya/lib/karya/worker_supervisor/runtime.rb

Comment thread core/karya/lib/karya/backend/descriptor.rb Outdated

feat: implement shared backend interface and model

f2b2707

niteshpurohit requested a review from Copilot May 2, 2026 20:22

Copilot started reviewing on behalf of niteshpurohit May 2, 2026 20:23 View session

Copilot AI reviewed May 2, 2026

View reviewed changes

refactor: clean up backend interface methods

d2827df

niteshpurohit merged commit 4ea53a3 into main May 3, 2026
22 checks passed

niteshpurohit deleted the feat/implement-the-shared-backend-interface-and-backend-selection-model branch May 3, 2026 13:16

Uh oh!

Conversation

niteshpurohit commented May 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

niteshpurohit commented May 2, 2026 •

edited

Loading